0078. tsconfig.json 快速入门
- 1. 🎯 本节内容
- 2. 🫧 评价
- 3. 🤔 什么是 tsconfig.json?
- 4. 🤔 如何创建 tsconfig.json?
- 5. 🤔 tsconfig.json 配置文件的基本结构是什么样的?
- 6. 🤔 常用编译选项有哪些?
- 7. 🤔 如何调试 tsconfig.json 配置?
- 8. 🔗 引用
1. 🎯 本节内容
- tsconfig.json 的作用
- 基本配置项说明
- 常见场景配置模板
- 配置调试技巧
- 最佳实践建议
2. 🫧 评价
tsconfig.json 是 TypeScript 项目的配置文件,它决定了编译器的行为、类型检查的严格程度以及输出文件的结构。虽然 TypeScript 可以在没有配置文件的情况下工作,但在实际项目中,合理的 tsconfig.json 配置是必不可少的。
该配置文件的复杂度在于:它有 100+ 个配置选项,每个选项都会影响编译行为。新手常见的问题是:
- 不知道哪些选项是必需的
- 不理解选项之间的依赖关系
- 照搬网上的配置导致问题
本节将从实用角度出发,介绍最常用的配置选项,并提供不同场景的配置模板。掌握这些内容后,你就能根据项目需求定制合适的 TypeScript 简单配置了。
3. 🤔 什么是 tsconfig.json?
tsconfig.json 是 TypeScript 项目的配置文件,用于指定:
| 配置类别 | 用途 | 示例选项 |
|---|---|---|
| 编译选项 | 控制编译器行为 | target, module, strict |
| 文件包含/排除 | 指定哪些文件需要编译 | include, exclude, files |
| 路径映射 | 配置模块解析 | paths, baseUrl |
| 类型检查 | 控制类型检查严格度 | strictNullChecks, noImplicitAny |
| 输出配置 | 控制编译产物 | outDir, declaration |
txt
有 tsconfig.json:
tsc # 按配置文件编译项目
tsc --watch # 监听模式
没有 tsconfig.json:
tsc file.ts # 只能编译单个文件
tsc file.ts --target ES2020 # 需要手动指定所有选项1
2
3
4
5
6
7
2
3
4
5
6
7
4. 🤔 如何创建 tsconfig.json?
4.1. 方法 1:使用命令 tsc --init 自动生成
bash
# 生成默认配置
tsc --init1
2
2
下面是目前 25.11 生成的 tsconfig.json 示例:
json
{
// Visit https://aka.ms/tsconfig to read more about this file
"compilerOptions": {
// File Layout
// "rootDir": "./src",
// "outDir": "./dist",
// Environment Settings
// See also https://aka.ms/tsconfig/module
"module": "nodenext",
"target": "esnext",
"types": [],
// For nodejs:
// "lib": ["esnext"],
// "types": ["node"],
// and npm install -D @types/node
// Other Outputs
"sourceMap": true,
"declaration": true,
"declarationMap": true,
// Stricter Typechecking Options
"noUncheckedIndexedAccess": true,
"exactOptionalPropertyTypes": true,
// Style Options
// "noImplicitReturns": true,
// "noImplicitOverride": true,
// "noUnusedLocals": true,
// "noUnusedParameters": true,
// "noFallthroughCasesInSwitch": true,
// "noPropertyAccessFromIndexSignature": true,
// Recommended Options
"strict": true,
"jsx": "react-jsx",
"verbatimModuleSyntax": true,
"isolatedModules": true,
"noUncheckedSideEffectImports": true,
"moduleDetection": "force",
"skipLibCheck": true,
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
4.2. 方法 2:继承社区模板
bash
# 安装基础配置
npm install --save-dev @tsconfig/node18
# 继承配置
{
"extends": "@tsconfig/node18/tsconfig.json",
"compilerOptions": {
// 自定义覆盖
}
}1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
4.3. 方法 3:手动创建 tsconfig.json 文件
json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true
},
"include": ["src//*"],
"exclude": ["node_modules", "dist"]
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
5. 🤔 tsconfig.json 配置文件的基本结构是什么样的?
json
{
// 继承其他配置
"extends": "./base-config.json",
// 编译选项
"compilerOptions": {
/* 基础选项 */
"target": "ES2020", // 目标 JS 版本
"module": "ESNext", // 模块系统
"lib": ["ES2020", "DOM"], // 包含的类型库
// ...
/* 严格检查 */
"strict": true, // 开启所有严格检查
// ...
/* 模块解析 */
"moduleResolution": "node", // 模块解析策略
"baseUrl": "./", // 基础路径
"paths": {
// 路径映射
"@/*": ["src/*"]
},
// ...
/* 输出 */
"outDir": "./dist", // 输出目录
"declaration": true, // 生成 .d.ts
"sourceMap": true // 生成 source map
// ...
},
// 包含的文件
"include": ["src//*"],
// 排除的文件
"exclude": ["node_modules", "dist"],
// 精确指定文件(不常用)
"files": ["src/main.ts"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"strict": true,
"esModuleInterop": true
},
"include": ["src"]
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
6. 🤔 常用编译选项有哪些?
6.1. 必知选项(按重要性排序)
| 选项 | 作用 | 推荐值 | 说明 |
|---|---|---|---|
| strict | 开启所有严格检查 | true | 包含若干个子选项 |
| target | 编译目标 | ES2020 | 根据运行环境选择 |
| module | 模块系统 | ESNext | 现代项目用 ESNext |
| lib | 包含的类型库 | ["ES2020", "DOM"] | 浏览器项目需要 DOM |
| outDir | 输出目录 | "./dist" | 编译产物位置 |
| rootDir | 源码根目录 | "./src" | 保持目录结构 |
| moduleResolution | 模块解析策略 | "node" | Node.js 风格解析 |
| esModuleInterop | ESM/CJS 互操作 | true | 兼容默认导入 |
| skipLibCheck | 跳过库文件检查 | true | 加快编译速度 |
6.2. strict 包含的选项
json
{
"compilerOptions": {
"strict": true
// 等价于:
// "noImplicitAny": true, // 禁止隐式 any
// "strictNullChecks": true, // 严格 null 检查
// "strictFunctionTypes": true, // 严格函数类型
// "strictBindCallApply": true, // 严格 bind/call/apply
// "strictPropertyInitialization": true, // 类属性必须初始化
// "noImplicitThis": true, // 禁止隐式 this
// "alwaysStrict": true // 生成 "use strict"
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
6.3. 不同开发场景下的一些常见配置示例
json
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"jsx": "react-jsx", // React 17+ 新 JSX 转换
"moduleResolution": "node",
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true
}
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
json
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs", // Node.js 使用 CJS
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"moduleResolution": "node",
"esModuleInterop": true,
"strict": true,
"skipLibCheck": true,
"types": ["node"] // 包含 Node.js 类型
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
json
{
"compilerOptions": {
"target": "ES2015", // 兼容性考虑
"module": "ESNext",
"declaration": true, // 生成 .d.ts
"declarationMap": true, // 生成 .d.ts.map
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"skipLibCheck": true
}
}1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
7. 🤔 如何调试 tsconfig.json 配置?
7.1. 查看实际生效的配置
bash
# 查看编译器使用的配置
tsc --showConfig
# 输出示例:
{
"compilerOptions": {
"target": "es2020",
"module": "esnext",
"strict": true,
...
},
"files": [],
"include": ["src//*"],
"exclude": ["node_modules", "dist"]
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
7.2. 检查哪些文件会被编译
bash
# 列出所有会被编译的文件
tsc --listFiles
# 输出示例:
/path/to/project/src/index.ts
/path/to/project/src/utils.ts
/path/to/project/node_modules/typescript/lib/lib.es2020.d.ts
...1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
7.3. 查看模块解析过程
bash
# 查看模块如何被解析
tsc --traceResolution
# 输出示例:
======== Resolving module 'lodash' from '/path/to/project/src/index.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module 'lodash' from 'node_modules' folder, target file type 'TypeScript'.
File '/path/to/project/node_modules/lodash.ts' does not exist.
File '/path/to/project/node_modules/lodash.tsx' does not exist.
...1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
7.4. 常见问题排查
bash
# 检查 include/exclude 配置
tsc --listFiles | grep "your-file.ts"
# 解决方案:
# 1. 确认文件路径在 include 中
# 2. 确认文件未在 exclude 中1
2
3
4
5
6
2
3
4
5
6
bash
# 检查模块解析
tsc --traceResolution > resolution.log
# 解决方案:
# 1. 检查 moduleResolution 设置
# 2. 检查 paths 配置
# 3. 检查 baseUrl 设置1
2
3
4
5
6
7
2
3
4
5
6
7
bash
# 逐步开启严格检查
{
"strict": false,
"noImplicitAny": true, // 先开启这个
"strictNullChecks": false // 逐步开启其他
}1
2
3
4
5
6
2
3
4
5
6
7.5. 配置验证工具
json
// 使用 JSON Schema 验证
{
"$schema": "https://json.schemastore.org/tsconfig",
"compilerOptions": {
// VS Code 会提供自动补全和错误检查
}
}1
2
3
4
5
6
7
2
3
4
5
6
7